本文彻底讲透了 Claude Code 中 CLAUDE.md 的作用、加载机制、编写方法和演进之道，帮你让 AI 更懂项目，开发效率倍增。原文：The Complete Guide to Claude Code: CLAUDE.md

梳理近几年 AI 编程工具的演进时间线，Claude Code 绝对是值得标记的重要节点。

Anthropic 在 2025 年 2 月把它推向开发者，当时还是早期公开预览版，到 2025 年 5 月开始，它已经走进了更多开发者的视野。

Claude Code 的特别之处不在于又给开发者加了一个聊天模型界面，而在于第一次让 AI Agent 真正走进了终端 —— 读取仓库、编辑文件、运行命令、修复问题，全程自己推进任务。

从那一刻开始，软件开发的重心已经在悄悄转移。

很长一段时间以来，开发者的核心工作都是手动实现，IDE 更多是帮我们做代码补全、搜索和分析的助手。而 Claude Code 把这个边界推得远了很多。

越来越多的时候，我们不再从「下一行代码写什么」开始思考，而是想清楚：目标是什么，约束有哪些，哪些文件可以改，做成什么样算完成。

开发过程正在从逐行手写代码转向通过清晰意图 + AI 协作驱动实现。这不是小版本功能升级，而是工作方式的真正重构，也是为什么很多开发者第一次用就真的感受到了 AI 自主完成编程任务的冲击力。

作为 Claude Code 理解项目的入口，CLAUDE.md 提供了 AI 需要的项目背景和协作规范，直接影响模型在代码库中工作的准确性和可靠性。

什么是 CLAUDE.md

CLAUDE.md 是一个 Markdown 文件，Claude Code 在每次会话开始时都会自动读取。

在这个文件里，可以写下指令、规则和偏好，Claude Code 在整个交互过程都会遵循这些约定。

网上有人玩过一个梗，用 2024 巴黎奥运会射击项目的对比图开玩笑说，Claude Code 用户分两种：

左边是全副武装，疯狂装各种插件；右边是土耳其神枪手淡定站着，一只手插兜，全靠一篇 CLAUDE.md。

虽然是玩笑，但话说得很对：与其花时间折腾花里胡哨的插件配置，不如静下心写好一篇 CLAUDE.md。

真正花心思写它的用户，往往能得到超出预期的体验，因为 CLAUDE.md 从根本上改变了 AI 和项目的交互方式。

打个比方：如果把 Claude Code 当成加入团队的新开发，那 CLAUDE.md 就是项目入职手册。

没有这本手册，新同事就得不停问基础问题：这个项目怎么构建？用什么测试框架？代码风格是什么样的？

有了手册，他第一天就能按照团队期望的方式高效开工。

CLAUDE.md 的核心价值： 把 Claude Code 从通用 AI 助手，变成为项目量身定制的开发工具。

CLAUDE.md 的加载机制

很多人刚接触 CLAUDE.md 时，以为它就是项目根目录下的一个简单的 Markdown 文件。

实际上不是这样，Claude Code 通过分层加载模型来读取记忆和指令 —— 不同位置的 CLAUDE.md 文件适用于不同作用域：有些影响你所有项目，有些只影响当前仓库，有些只在特定子目录生效。

这也是为什么大家在实际使用中经常困惑：为什么同一条规则在 A 项目生效，到 B 项目就被覆盖了？为什么明明写了规则，Claude Code 在某个目录就是不遵守？

这些问题说到底，都是对加载机制理解不够。

文件层级结构

从整体上看，主要有这几种类型：

• 项目级 ./CLAUDE.md 或者 ./.claude/CLAUDE.md：日常最常用，通过版本控制共享，定义了 Claude Code 在该仓库中的默认行为
• 用户级 ~/.claude/CLAUDE.md：更像是你的全局个人偏好配置
• 项目本地 CLAUDE.local.md：用来写你不想提交但又想在当前项目生效的笔记
• 项目子目录 ./<子目录>/CLAUDE.md：针对特定子目录的指令
• 高级组织方式 .claude/rules/：有些团队会把规则拆分到这个目录，更模块化管理

本文我们聚焦 CLAUDE.md 本身，高级玩法就不展开了。

加载规则

Claude Code 读取这些文件时，大致遵循这些规则：

Claude Code 启动时，首先读取当前工作目录相关的 CLAUDE.md 文件。

用户级的 ~/.claude/CLAUDE.md 也会作为更高级别默认偏好被包含进来。

子目录中的 CLAUDE.md 并不会一开始全部加载，只有当 Claude Code 实际读取那些目录内容时才会加载。

当多个 CLAUDE.md 同时激活时，通常适用最近作用域规则 —— 越接近当前任务、作用域越窄的指令，优先级越高。

同一层级中，越明确具体的规则，比模糊笼统的陈述更容易被一致遵守。

冲突解决

当不同的 CLAUDE.md 文件之间发生冲突时，最近作用域原则是最容易理解的规则。

规则越靠近当前任务，适用范围越窄，优先级通常就越高。

比如，用户级 CLAUDE.md 说用 4 空格缩进，但项目根目录的 CLAUDE.md 明确说用 2 空格缩进，那么在这个项目里，Claude Code 就会遵循 2 空格缩进。

这点很重要 —— 你不仅要知道可以存在多个 CLAUDE.md，还要理解每个规则适用于什么作用域，冲突发生时哪个覆盖哪个。

如何编写 CLAUDE.md

用 /init 快速起步

最简单的起步方式，就是在项目根目录运行 Claude Code 的 /init 命令，让它帮你生成第一版草稿：

$ claude
> /init

/init 会扫描技术栈、目录结构和常用命令，然后生成 CLAUDE.md 文件，给你一个基础起点骨架。

但这只能解决怎么从空白文件开始的问题，不代表生成出来的就真的适合你的项目。

拿到草稿后，通常至少需要一轮编辑。原因很简单：/init 生成的内容往往又广又全，它把能检测到的信息都塞进去了，但有些信息对你的项目其实不重要，有些信息本身没错，但对指导 Claude Code 工作来说还不够有用。

CLAUDE.md 不是越长就越好。一方面，它占用上下文窗口空间；另一方面，信息太分散太笼统，Claude Code 反而更难识别真正重要的约束。

更好的做法是：先删掉那些低价值、通用型、或者在别处已经有文档的冗余信息，然后加上只有你们团队才知道的项目知识，特别是那些最容易让 Claude Code 犯错的细节。

第一次写，从最有用的信息开始

第一次写 CLAUDE.md，不需要一开始就追求完整。更重要的是，从那些最直接影响 Claude Code 表现的信息开始写起。

换句话说，优先放缺失了就容易出错的内容，而不是那些只是让文件看起来完整的内容。

最有价值先加的信息，通常分这几类：

• 常用命令：构建、测试、lint、本地开发命令，不用每次让 Claude Code 猜
• 项目特定约束和坑：哪些目录不能改，哪些表用软删除，哪些接口必须走特定中间件
• 基本工作流：分支命名、pre-commit 检查、PR 基本要求
• 核心架构上下文：单体仓库中每个目录的职责，哪些模块不能跨层

如果某条信息不能帮助 Claude Code 更快理解项目，也不能减少常见错误，那就没必要急着放进文件。CLAUDE.md 的价值不在于覆盖一切，而在于清晰传递最重要的项目事实和协作约束。

文件变大后，用 @imports 拆分

随着项目变复杂，规则越来越多，不要把所有东西都塞在一个文件里。

这时可以用 @imports 把更详细的指引放到独立文件，然后从主 CLAUDE.md 引用它们：

# Project Instructions

See @README.md for project overview.
See @package.json for available commands and scripts.
See @docs/testing.md for testing conventions.
See @docs/api-guidelines.md for API design rules.

这样做的好处是：主文件可以继续保留最常用、最需要第一眼看到的信息，而更详细的规范、流程和约定可以单独维护。

至于要模块化到什么程度，哪些内容值得拆分，我会在后面最佳实践部分讲到。

CLAUDE.md 如何持续演进

CLAUDE.md 不是那种写一次就再也不用碰的文件，而更像是项目不断进化的记忆。

真正变得有价值的部分，往往不是一次性空想出来的，而是通过反复协作、纠正和复盘，逐步打磨出来的。

通过协作问题持续改进

当然，可以从 /init 生成的草稿开始，但后续该往 CLAUDE.md 里加什么，通常不是来自想象，而是来自日常工作中不断发现的具体协作问题。

它不应该依赖某个人偶尔随机添加笔记，而应该成为整个团队持续记录和保存项目经验的地方。

这些问题往往非常具体：

• Claude Code 一直用 npm 不用 pnpm？加一条规则
• Claude Code 一直把生成的测试文件放错目录？把正确的测试文件放置规则写清楚
• Claude Code 改了 DB schema 文件但忘记重新构建底层模块？把依赖关系和需要的构建步骤写明白

每次你不得不手动纠正 Claude Code，这其实就是一个强烈信号：某条项目知识还没写到 CLAUDE.md 里。如果团队里同一个更正已经发生过两三次，通常就足够说明，这条规则应该变成共享的长期记忆了。

用 /reflection 定期复盘

前面这种方法，还是依赖人们在使用过程中发现问题，然后记得更新规则。/reflection 的价值在于，它把这变成了可重复的收尾步骤。

每次会话结束，你可以让 Claude Code 总结这一轮协作中有哪些内容值得加入 CLAUDE.md，然后把这些点变成更稳定的项目规则。

严格来说，/reflection 不是什么神秘的内置能力，它本质上就是一个提示词，打包成可以重复调用的命令。如果你想看它的原始内容，可以直接看这个 reflection gist。

这个提示词的核心思想是，让 Claude Code 回顾刚刚结束的会话，判断哪些经验已经足够稳定，可以从聊天上下文变成 CLAUDE.md 中的持久规则。用户确认后，Claude Code 会更新 CLAUDE.md，不修改其他任何文件。

配置也很简单：Anthropic 官方文档提到，放在 ~/.claude/commands/ 下的 Markdown 文件会自动变成用户级命令，文件名就是命令名。所以你可以把这个提示词保存为：

~/.claude/commands/reflection.md

然后就可以直接在 Claude Code 中运行：

/reflection

Claude Code 会按照提示回顾会话，用确认过的规则更新 CLAUDE.md。这让 CLAUDE.md 的演进从人们偶尔记得做的事情，变成每次会话后都可以发生的稳定步骤。

用 Insights 报告优化

前面两种方法都更紧密绑定在单次协作会话上，而 Insights 能让你拉远视角，观察更长一段时间的使用情况。这样更容易看到哪些问题一直在重复出现，哪些习惯已经稳定，哪些信息值得正式加入 CLAUDE.md。

Insights 是 Claude Code v2.1.x 引入的分析命令，主要用来分析你的 Claude Code 使用历史，生成报告。报告中有一部分内容直接给出了如何改进 CLAUDE.md 的建议，这让它成为持续演进的重要路径。

用起来很简单：进入 Claude Code 后，运行 /insights 命令。完成后，你可以在 ~/.claude/usage-data 目录找到生成的 HTML 报告，在里面回顾你一段时间的使用模式和相关建议。

比如，你可能发现自己经常提醒 Claude Code 使用某组测试命令，经常告诉它不要碰某些生成目录，经常对同一类任务重复同样的背景信息。如果这些事情在多个会话中都会出现，那么可能就不应该一直埋在聊天记录里，而应该晋升到 CLAUDE.md 中。

从这个角度看，Insights 报告就是帮助 CLAUDE.md 持续进化的工具，它给出的修改建议，对判断哪些内容已经成熟到值得正式记录特别有用。

更有效的演进节奏

把上面这些方法串起来，自然的演进节奏通常是这样的：

1. 从 /init 开始，快速得到可用的第一版草稿
2. 记录日常协作中遇到的问题，把重复出现的更正写回 CLAUDE.md
3. 每次会话结束运行 /reflection，把本次会话的经验变成项目规则
4. 定期回顾 Insights 报告，识别更长时间跨度内的重复模式
5. 持续修剪收紧文件，删除过时、冗余、低价值的规则

通过这种方式演进出来的 CLAUDE.md，通常比第一天就试图穷尽一切的版本有用得多，因为它不是抽象设计出来的，而是从真实协作中一步步打磨出来的。

CLAUDE.md 最佳实践

很多人以为 CLAUDE.md 不生效是因为没加载到，但实际使用中，更常见的情况是：Claude Code 确实看到了文件，但它判断大部分内容和当前任务关联性不大，因此没有特意依赖。

换句话说，真正的问题往往不只是加载机制，而在于内容是否足够相关、足够具体、足够有长期保留价值。

所以这一节不讲怎么一直加规则，而是想聊聊如何判断什么值得保留。

保持简洁，优先保留高价值信息

CLAUDE.md 本质上是给 Claude Code 额外的上下文。这意味着它越长，消耗的上下文就越多，留给实际任务的空间就越少。

更重要的是，当文件变得太拥挤，模型更容易把它当成低相关性的背景材料。

所以主文件中，最值得保留的内容通常就是短短几类：高频命令、项目核心约束、容易踩坑的历史经验、每次有人进入仓库都可能用到的背景信息。

至于那些只在罕见情况下适用的内容，或者听起来不错但没有明确执行路径的陈述，宁可留在外面，也不要为了让文件看起来全面就塞进去。

具体，让规则真正可执行

很多 CLAUDE.md 文件表面看起来完整，但实际用起来帮不上什么忙，因为很多陈述方向对了，但没有给具体任务提供具体指导。

像「注意代码质量」、「遵循项目约定」、「修改前先理解上下文」这些话听起来没问题，但在具体场景中，几乎帮不上 Claude Code 做更好的决策。

真正有帮助的写法，是写到可以直接遵循的程度：测试该用什么命令，哪些目录不能编辑，提交前是否必须跑 lint，API 层属于哪个目录，什么情况下必须加测试。

写得越具体，Claude Code 在日常工作中就越容易理解你的真实意图。

传递意图，不只是列规则

好的 CLAUDE.md 不只是列规则，更重要的是帮助 Claude Code 理解规则背后的意图。因为很多真实任务不会正好落在规则检查表的边界上。

只有理解了团队为什么这么设计，为什么会有这个约束，在新场景下做出的决策才更可能符合你的预期。

比如，如果你只写「不要修改 src/generated/ 下的文件」，这仍然是一条规则。但如果你更进一步，解释清楚这些文件是从 OpenAPI schema 自动生成的，真正的数据源是 schema 和生成工作流，而不是生成的输出，那么下次相关任务出现时，Claude Code 就能理解这个限制存在的原因，也更可能改对地方。

渐进式披露，主文件保持克制

不是所有信息都该放在根目录的 CLAUDE.md 里。更好的做法通常是：先把最常用、稳定、跨任务的信息放在主文件，内容增长后，用 @imports 拆分，或者在不同目录级别放多个 CLAUDE.md 文件。

前者改善结构和可维护性，后者让某些局部规则只有当 Claude Code 实际进入相关目录时才生效。

好处不只是文件看起来更干净。更重要的是，它减少了每次会话一开始就倒进上下文的无关信息。保持主文件克制，只在需要时才展开细节——这样 CLAUDE.md 才会像一本深思熟虑的协作指南，而不是越堆越多的项目琐事堆。

最后还要再强调一点：千万不要把 API 密钥、密码、token 或任何其他秘钥放在 CLAUDE.md 里，因为它通常会进入版本控制。你把凭证写在那里，就等于把它暴露给所有能访问仓库的人。

与其他 AI 编程工具对比

在 Claude Code 之外的类似 AI 编程工具中，大多数现在都有自己的指令文件。但放到今天看，真正值得比较的不只是文件名，更重要的问题是：每个工具如何使用这个文件，哪些能力放在文件之外。

不只名字不同，机制也不同

从指令系统设计的角度看，Claude Code 和 Gemini CLI 其实更接近。它们都把这些文件当成持久记忆或者注入模型的上下文。

区别在于，Claude Code 对 CLAUDE.md 有更清晰的层级结构，更容易组合跨项目的多个上下文文件。

Gemini CLI 也能从项目中读取多个 GEMINI.md 文件，但更多是用简单方式拼接在一起，而且甚至允许你把默认文件重命名为 AGENTS.md，这在生态兼容性上更开放。

Codex、OpenCode 和 Droid 更像是同一演化方向的不同分支。这三个工具都在向 AGENTS.md 收敛，但共享的不只是共同文件名，还倾向于把 AGENTS.md 作为统一入口，同时把更高级的能力放在文件之外。

Codex 的重点是把 AGENTS.md 变成可复用的跨工具指令格式。OpenCode 和 Droid 的重点更多是围绕 AGENTS.md 扩展更丰富的协作能力。换句话说，走这条路径的话，AGENTS.md 更像是起点而不是整个系统。

正在形成的趋势

真正值得关注的，已经不再是文件本身，而是这些工具背后的指令系统正在逐步收敛。

CLAUDE.md 仍然代表了非常有辨识度的记忆设计，特别是在分层加载和项目上下文管理方面，依然有明显优势。

与此同时，AGENTS.md 正在成为越来越强的跨工具格式。到 2025 年末，OpenAI 已经把 AGENTS.md 贡献给了 Agentic AI Foundation，明确将其描述为一种简单、开放、可互操作的标准。Gemini CLI、OpenCode、Droid 等也都在不同程度上朝着这个约定靠拢。

这意味着未来，在不同 AI 编程 Agent 之间切换成本可能会持续降低。但在当前阶段，文件名可能在收敛，但能力模型还远未统一。有的工具强调分层记忆，有的强调 Agent 编排，有的把技能、subagent、插件、组织级配置都放在指令文件之外。

所以 CLAUDE.md 的价值，不只是文件本身，而是它背后组织项目上下文的整套方式。

总结

本文从 CLAUDE.md 是什么开始，梳理了加载方式、编写方法、演进方式、最佳实践，以及和其他类似工具指令系统的关系。

真正重要的是理解它背后更宏观的模式：一种组织项目上下文、保存协作约束、让 AI Agent 更可靠参与开发的方式。

实际使用中，CLAUDE.md 效果最好的时候，是从一个可用版本开始，然后通过真实协作不断添加、修剪、收紧，而不是从第一天就试图写出包罗万象的文档。

不管未来不同工具的文件名和实现如何演进，这个基本思想仍然会有价值：把项目经验变成长期规则，让 AI 更一致的理解上下文。这就是为什么 CLAUDE.md 值得认真理解。

参考文献

• How to Write a Good CLAUDE.md File
• Writing a good CLAUDE.md
• Understanding CLAUDE.md Loading in Large Monorepos
• Manage Claude's memory
• AGENTS.md